/*
 *  SPAGL Copyright (C) 2008 Sam Pottinger
 *  This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser 
 *  General Public License as published by the Free Software Foundation; either version 2.1 of the License, or 
 *  (at your option) any later version. This library is distributed in the hope that it will be useful, but 
 *  WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
 *  See the GNU Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public License along with this library; if not, 
 *  write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 
 */

package spagcore;

/**
 * An interface to standardize the use of list widgets from which elements can be selected
 * @author Sam Pottinger
 */
public interface SpaglCoreList extends SpaglCoreWidget, SpaglFontCapable, SpaglCoreEventGenerator {
	
	public static int SINGLE = 0;
	public static int MULTI = 1;
	
	/**
	 * Adds an object to this list as an option
	 * @param newElement The new object to be added
	 */
	public void addElement(Object newElement);
	
	/**
	 * Adds an object to this list as an option at a given position
	 * @param position The integer position where the object will be inserted
	 * @param newElement The new object to be added
	 */
	public void addElement(int position, Object newElement);
	
	/**
	 * Sets the list of options available
	 * @param newElementList A list of objects to be used as selection options
	 */
	public void setElementList(Object[] newElementList);
	
	/**
	 * Removes the object at a given index from this list
	 * @param i The index of the option to be removed
	 */
	public void removeElement(int i);
	
	/**
	 * Completely clears all selection options from this list
	 */
	public void removeAllElements();
	
	/**
	 * Gets the index of the option selected in this list. If multiple selections are allowed it will return the most recent choice.
	 * @return The index of the object highlighted in this widget
	 */
	public int getSelectedIndex();
	
	/**
	 * Gets the indicies currently selected in this list
	 * @return An array of indicies currently highlighted in this widget
	 */
	public int[] getSelectedIndicies();
	
	/**
	 * Removes any selection made by the user and turns off any highlighted options
	 */
	public void clearSelection();
	
	/**
	 * Sets the option to be highlighted as selected in this list
	 * @param i The index of the object to be highlighted as selected
	 */
	public void setSelectedIndex(int i);
	
	/**
	 * Sets the options to be highlighted as selected in this list
	 * @param i The indicies of the objects to be highlighted as selected
	 */
	public void setSelectedIndicies(int[] i);

}
